%$Id$
\documentclass[a4paper,12pt]{article}
\usepackage[utf8]{inputenc}
\usepackage{pslatex}
\usepackage{eurosym}
\usepackage{amssymb}
\usepackage{latexsym}
\usepackage[dvips]{graphicx}
\usepackage{delarray}
\usepackage{amsmath}
%\usepackage{bbm}
%\usepackage{bbold}
%\usepackage{accents}
\usepackage{subfigure}
\usepackage{multirow}
\usepackage{fancyhdr}
%\usepackage{tocbibind}
%\usepackage{bibtex}
%\usepackage{wrapfig}
\usepackage{color}
\usepackage{hyperref}
%\usepackage{fmtcount}
\usepackage{parskip}

\newcommand{\command}[1]{\texttt{#1}}
\newcommand{\file}[1]{``\texttt{#1}''}
\newcommand{\directory}[1]{`\texttt{#1}'}
\newcommand{\name}[1]{\textsc{#1}}
\newcommand{\code}[1]{\texttt{#1}}

\frenchspacing

\graphicspath{{./fig/}{./png/}}

\setlength{\hoffset}{-1in}
\setlength{\textwidth}{7.5in}
\setlength{\voffset}{-0.5in}
\setlength{\textheight}{9.5in}

\title{Pencil Code: Quick Start guide}

\author{Illa R. Losada, Michiel Lambrechts, Elizabeth Cole, Philippe Bourdin}


\begin{document}
\maketitle

\tableofcontents

\newpage


\section{Required software}

\subsection{\name{Linux}}
A \name{Fortran} and a \name{C} compiler are needed to compile the code.
Both compilers should belong to the same distribution package and version (e.g. GNU GCC or Intel).

\subsection{\name{MacOS X}}
For \name{Mac}, you first need to install \name{Xcode} from the
website \url{http://developer.apple.com/}, where you have to register as a member.
Alternatively, an easy to install \command{gfortran} binary package can be found at the website \url{http://gcc.gnu.org/wiki/GFortranBinaries}. Just download the archive and use the installer contained therein.
It installs into \directory{/usr/local/gfortran} with
a symbolic link in \directory{/usr/local/bin/gfortran}. It might be necessary to add
the following line to the \file{.cshrc}-file in your \directory{/home} folder:
\begin{verbatim}
  setenv PATH /usr/local/bin:\$PATH
\end{verbatim}


\section{Download the Pencil Code}
The Pencil Code is an open source code written mainly in \name{Fortran} and available under GPL.
General information can be found at our official homepage:

\url{http://pencil-code.nordita.org/}.

The latest version of the code can be downloaded with \command{svn}. In the
directory where you want to put the code, type:
\begin{verbatim}
  svn checkout https://github.com/pencil-code/pencil-code/trunk/ pencil-code
\end{verbatim}

Alternatively, you may also use \command{git}:
\begin{verbatim}
  git clone https://github.com/pencil-code/pencil-code.git
\end{verbatim}

More details on download options can be found here: \url{http://pencil-code.nordita.org/download.php}

The downloaded \directory{pencil-code} directory contains several sub-directories:
\begin{enumerate}
  \item \directory{doc}: you may build the latest manual as PDF by issuing the command \command{make} inside this directory
  \item \directory{samples}: contains many sample problems
  \item \directory{config}: has all the configuration files
  \item \directory{src}: the actual source code
  \item \directory{bin} and \directory{lib}: supplemental scripts
  \item \directory{idl}, \directory{python}, \directory{julia}, etc.: data processing for diverse languages
\end{enumerate}


\section{Configure the shell environment}

You need to load some environment variables into your shell.
Please change to the freshly downloaded directory:
\begin{verbatim}
  cd pencil-code
\end{verbatim}

Probably you use a \command{sh}-compatible shell (like the \name{Linux} default shell \command{bash}), there you just type:
\begin{verbatim}
  . sourceme.sh
\end{verbatim}

(In a \command{csh}-compatible shell, like \command{tcsh}, use this alternative: \command{source sourceme.csh} )


\section{Your first simulation run}

\subsection{Create a new run-directory}

Now create a run-directory and clone the input and configuration files from one of the samples that fits you best to get started quickly (here from \directory{pencil-code/samples/1d-tests/jeans-x}):
\begin{verbatim}
  mkdir -p /data/myuser/myrun/src
  cd /data/myuser/myrun
  cp $PENCIL_HOME/samples/1d-tests/jeans-x/*.in ./
  cp $PENCIL_HOME/samples/1d-tests/jeans-x/src/*.local src/
\end{verbatim}
Your run should be put outside of your \directory{/home} directory, if you expect to generate a lot of data and you have a tight storage quota in your \directory{/home}.

\subsection{Linking to the sources}

One command sets up all needed symbolic links to the original Pencil Code directory:
\begin{verbatim}
  pc_setupsrc
\end{verbatim}

\subsection{Makefile and parameters}

Two basic configuration files define a simulation setup: \file{src/Makefile.local} contains a list of modules that are being used, and \file{src/cparam.local} defines the grid size and the number of processors to be used.
Take a quick look at these files...


\subsubsection{Single-processor}
An example \file{src/Makefile.local} using the module for only one processor would look like:
\begin{verbatim}
  MPICOMM=nompicomm
\end{verbatim}

For most modules there is also a \file{no}-variant which switches that functionality off.

In \file{src/cparam.local} the number of processors needs to be set to \code{1} accordingly:
\begin{verbatim}
  integer, parameter :: ncpus=1,nprocx=1,nprocy=1,nprocz=ncpus/(nprocx*nprocy)
  integer, parameter :: nxgrid=128,nygrid=1,nzgrid=128
\end{verbatim}

\subsubsection{Multi-processor}
If you like to use \name{MPI} for multi-processor simulations, be sure that you have a \name{MPI} library installed and change \file{src/Makefile.local} to use \name{MPI}:
\begin{verbatim}
  MPICOMM=mpicomm
\end{verbatim}

Change the \code{ncpus} setting in \file{src/cparam.local}.
Think about how you want to distribute the volume on the processors --- usually, you should have 128 grid points in the x-direction to take advantage of the SIMD processor unit.
For compilation, you have to use a configuration file that includes the \file{\_MPI} suffix, see below.

\subsection{Compiling...}

In order to compile the code, you can use a pre-defined configuration file corresponding to your compiler package.
E.g. the default compilers are \command{gfortran} together with \command{gcc} and the code is being built with default options (not using \name{MPI}) by issuing the command:

\begin{verbatim}
  pc_build
\end{verbatim}

Alternatively, for multi-processor runs (still using the default \name{GNU-GCC} compilers):
\begin{verbatim}
  pc_build -f GNU-GCC_MPI
\end{verbatim}

\subsubsection{Using a different compiler (optional)}

If you prefer to use a different compiler package (e.g. with \name{MPI} support or using \command{ifort}), you may try:

\begin{verbatim}
  pc_build -f Intel
  pc_build -f Intel_MPI
  pc_build -f Cray
  pc_build -f Cray_MPI
\end{verbatim}

More pre-defined configurations are found in the directory \file{pencil-code/config/compilers/*.conf}.

\subsubsection{Changing compiler options (optional)}

Of course you can also create a configuration file in any subdirectory of \directory{pencil-code/config/hosts/}.
By default, \command{pc\_build} looks for a config file that is based on your \code{host-ID}, which you may see with the command:
\begin{verbatim}
  pc_build -i
\end{verbatim}
You may add your modified configuration with the filename \file{host-ID.conf}, where you can change compiler options according to the Pencil Code manual.
A good host configuration example, that you may clone and adapt according to your needs, is \file{pencil-code/config/hosts/IWF/host-andromeda-GNU\_Linux-Linux.conf}.

\subsection{Running...}

The initial conditions are set in \file{start.in} and the parameters for the main simulation run can be found in \file{run.in}.
In \file{print.in} you can choose which quantities are written to the file \file{data/time\_series.dat}.

Be sure you have created an empty \directory{data} directory.
\begin{verbatim}
  mkdir data
\end{verbatim}

It is now time to run the code:
\begin{verbatim}
  pc_run
\end{verbatim}
If everything worked well, your output should contain the line
\begin{verbatim}
  start.x has completed successfully
\end{verbatim}
after initializing everything successfully. It would then start running,   
printing in the console the quantities specified in \file{print.in}, for 
instance,
\begin{verbatim}
---it--------t-------dt------rhom------urms------uxpt-----uypt-----uzpt-----
       0      0.00 4.9E-03 1.000E+00  1.414E+00 2.00E+00 0.00E+00 0.00E+00
      10      0.05 4.9E-03 1.000E+00  1.401E+00 1.98E+00 0.00E+00 0.00E+00
      20      0.10 4.9E-03 1.000E+00  1.361E+00 1.88E+00 0.00E+00 0.00E+00 
      .......
\end{verbatim}
ending with
\begin{verbatim}
  Simulation finished after        xxxx  time-steps
  .....
  Wall clock time/timestep/meshpoint [microsec] = ...
\end{verbatim}
An empty file called \file{COMPLETED} will appear in your run directory once 
the run is finished.


If you work with one of the samples or an identical setup in a new working directory, you can verify the correctness of the results
by checking against reference data, delivered with each sample:
\begin{verbatim}
  diff reference.out data/time_series.dat
\end{verbatim}

Welcome to the world of Pencil Code!

\subsection{Troubleshooting...}

If compiling fails, please try the following --- with or without the optional \command{\_MPI} for \name{MPI} runs:
\begin{verbatim}
  pc_build --cleanall
  pc_build -f GNU-GCC_MPI
\end{verbatim}

If some step still fails, you may report to our mailing list: \url{http://pencil-code.nordita.org/contact.php}.
In your report, please state the exact point in this quick start guide that fails for you (including the full error message) --- and be sure you precisely followed all non-optional instructions from the beginning.

In addition to that, please report your operating system (if not \name{Linux}-based) and the shell you use (if not \command{bash}).
Also please give the full output of these commands:
\begin{verbatim}
  bash
  cd path/to/your/pencil-code/
  source sourceme.sh
  echo $PENCIL_HOME
  ls -la $PENCIL_HOME/bin
  cd samples/1d-tests/jeans-x/
  gcc --version
  gfortran --version
  pc_build --cleanall
  pc_build -d
\end{verbatim}

If you plan to use \name{MPI}, please also provide the full output of:
\begin{verbatim}
  mpicc --version
  mpif90 --version
  mpiexec --version
\end{verbatim}

\section{Data post-processing}

\subsection{IDL visualization (optional, recommended)}
% The goal of this section is to demonstrate the general work flow with a very simple example.

\subsubsection{GUI-based visualization (recommended for quick inspection)}
The most simple approach to visualize a Cartesian grid setup is to run the Pencil Code GUI and to select the files and physical quantities you want to see:
\begin{verbatim}
IDL> .r pc_gui
\end{verbatim}
If you miss some physical quantities, you might want to extend the two IDL routines \command{pc\_get\_quantity} and \command{pc\_check\_quantities}. Anything implemented there will be available in the GUI, too.

\subsubsection{Command-line based processing of ``big data''}
Please check the documentation inside these files:
\begin{center}
\begin{tabular}{|l|l|}\hline
  \file{pencil-code/idl/read/pc\_read\_var\_raw.pro} & efficient reading of raw data\\\hline
  \file{pencil-code/idl/read/pc\_read\_subvol\_raw.pro} & reading of sub-volumes\\\hline
  \file{pencil-code/idl/read/pc\_read\_slice\_raw.pro} & reading of any 2D slice from 3D snapshots\\\hline
  \file{pencil-code/idl/pc\_get\_quantity.pro} & compute physical quantities out of raw data\\\hline
  \file{pencil-code/idl/pc\_check\_quantities.pro} & dependency checking of physical quantities\\\hline
\end{tabular}
\end{center}
in order to read data efficiently and compute quantities in physical units.

\subsubsection{Command-line based data analysis (may be inefficient)}
Several \name{idl}-procedures have been written
(see in \directory{pencil-code/idl}) to facilitate inspecting the data
that can be found in raw format in \directory{jeans-x/data}.
For example, let us inspect the time series data
\begin{verbatim}
IDL> pc_read_ts, obj=ts
\end{verbatim}
The structure \code{ts} contains several variables that can be inspected by
\begin{verbatim}
IDL> help, ts, /structure
** Structure <911fa8>, 4 tags, length=320, data length=320, refs=1:
   IT              LONG      Array[20]
   T               FLOAT     Array[20]
   UMAX            FLOAT     Array[20]
   RHOMAX          FLOAT     Array[20]
\end{verbatim}
The diagnostic \code{UMAX}, the maximal velocity, is available since it was set
in \file{jeans-x/print.in}. Please check the manual for more information about the input files.

We plot now the evolution of \code{UMAX} after the initial perturbation that is defined in \file{start.in}:
\begin{verbatim}
IDL> plot, ts.t, alog(ts.umax)
\end{verbatim}
% TODO Include screen shot

The complete state of the simulation is saved as snapshot files in
\file{jeans-x/data/proc0/VAR*} every \code{dsnap} time units,
as defined in \file{jeans-x/run.in}.
These snapshots, for example \file{VAR5}, can be loaded with:
\begin{verbatim}
IDL> pc_read_var, obj=ff, varfile="VAR5", /trimall
\end{verbatim}

Similarly \code{tag\_names} will provide us with the available variables:
\begin{verbatim}
IDL> print, tag_names(ff)
T X Y Z DX DY DZ UU LNRHO POTSELF
\end{verbatim}

The logarithm of the density can be inspected by using a GUI:
\begin{verbatim}
IDL> cslice, ff.lnrho
\end{verbatim}

Of course, for scripting one might use any quantity from the \code{ff} structure, like calculating the average density:
\begin{verbatim}
IDL> print, mean(exp(ff.lnrho))
\end{verbatim}


\subsection{Python visualization (optional)}
Be advised that the \name{Python} support is still not complete or as feature-rich as for \name{IDL}.
Furthermore, we move to \name{Python3} in 2020, and not all the routines have 
been updated yet.

\subsubsection{Python module requirements}
 

In this example we use the modules: \code{numpy} and \code{matplotlib}.
A complete list of required module is included in 
\file{pencil-code/python/pencil/README}.


\subsubsection{Using the 'pencil' module}
After sourcing the \file{sourceme.sh} script (see above), you should be able to import the \code{pencil} module:

\begin{verbatim}
import pencil as pc
\end{verbatim}

Some useful functions:
\begin{center}
\begin{tabular}{|l|l|}\hline
\file{pc.read.ts} & read \file{time\_series.dat} file. Parameters are added as 
members of the class\\\hline
\file{pc.read.slices} & read 2D slice files and return two arrays: 
(nslices,vsize,hsize) and (time)\\\hline
\file{pc.visu.animate\_interactive} & assemble a 2D animation from a 3D 
array\\\hline
%× & ×\\\hline
%× & ×\\\hline
%× & ×\\\hline
\end{tabular}
\end{center}

Some examples of postprocessing with \name{Python} can be found in the 
\name{Pencil} wiki:


\url{https://github.com/pencil-code/pencil-code/wiki/PythonForPencil}.

% This is out of the scope of a "quick start" guide.
% One might better implement this as an "highlight" on the website:
% \section{Another example: helically forced turbulence}
% \input{example2}


\end{document}
